Skip to content

P0–P2 polish: screenshots, sample report, Limitations, Contact, sister cross-links#1

Merged
CreatmanCEO merged 1 commit into
masterfrom
polish-readme-and-meta
May 5, 2026
Merged

P0–P2 polish: screenshots, sample report, Limitations, Contact, sister cross-links#1
CreatmanCEO merged 1 commit into
masterfrom
polish-readme-and-meta

Conversation

@CreatmanCEO
Copy link
Copy Markdown
Owner

Summary

The existing 1,072-line README is the most thorough among all author's repos (origin story, 4-layer detection engine, comparison vs MVT/PiRogue/AV, real-world Xiaomi case study, AI adaptive reports, Suricata/Zeek docs). This PR is additive, not destructive — it adds what was missing while preserving everything strong.

Plus a separate operational fix that landed on production along the way.

What's added

Screenshots gallery (right after badges)

  • 01-onboarding-and-vpn.webp — three-screen onboarding flow (greeting, privacy disclaimer "we don't read messages — only what your phone connects to", VPN-client picker)
  • 02-scan-and-report-delivery.webp — three-screen scan flow (start, two VPN-key delivery modes, final report)
  • Caption clarifies UI is in Russian (default locale); English fully supported

Sample scan report (two formats)

  • docs/reports/sample-scan-report.md — anonymised real report from 2026-03-16 with 3 CRITICAL findings (SSH / Telnet / RTSP — strong indicators of remote-control implants) and 6 HIGH-severity threat-intel IPs
  • docs/reports/sample-scan-report.html — same data as standalone HTML with inline dark-theme CSS — matches the format the bot actually delivers

Limitations & known failure modes

8 honest constraints — encrypted-payload blindness, JA3 evasion, detection lag, mobile-only scope, network-side only, VPN-trust requirement, false positives, no on-device remediation. Critical for a security tool's credibility.

Contact section

4 explicit channels — live bot, Telegram for general, GitHub Issues for bugs/rules, email for security researchers / responsible disclosure / press / commercial.

Related — Claude Code ecosystem

Cross-links to all 7 sister repos by the same author.

CI + meta

  • Three new badges: Stars, Validate CI, "@secure_scanbot LIVE"
  • CHANGELOG.md reconstructing showcase history
  • CONTRIBUTING.md with Phase-2 readiness priorities + explicit responsible-disclosure clause
  • .github/workflows/validate.yml — link checker, HTML parse, asset existence
  • Author signature expanded (Nick Podolyak with all professional channels)

README.ru.md mirrored

All new sections translated.

Operational fix (separate from this PR, already applied on VPS)

security-scanner-bot.service had been crash-looping (status=203/EXEC) since 2026-04-15 06:46 UTC because /root/security-scanner/venv/ was removed from disk. systemd attempted 170,678 restarts before the fix. The venv has been recreated, dependencies reinstalled (aiogram 3.4.1, aiohttp 3.9.3, aiosqlite 0.19.0, nest_asyncio + analysis stack), service is now active (running). Bot is live again at @secure_scanbot. Documented in CHANGELOG.md 0.2.0.

Excluded (deliberately)

  • No rewrite of the existing 1,072-line README — additive only
  • Default branch rename master → main deferred (affects external bookmarks)
  • awesome-claude-code submission (channel locked for non-collaborators)

Test plan

  • LICENSE and CHANGELOG.md present
  • Sample HTML report parses without error
  • All docs/* assets referenced from both READMEs exist
  • All internal Markdown links resolve from README / README.ru.md / CHANGELOG / CONTRIBUTING / sample-scan-report.md
  • Screenshot WebP files are non-empty (167 KB / 167 KB)
  • Bot operationally restored to active polling

🤖 Generated with Claude Code

…r cross-links

The existing 1,072-line README is the most thorough among all author's repos.
This PR adds what was missing without rewriting the strong content already there.

Added (preserving everything that was already strong)
- Two real-world bot screenshots in a "What it looks like" gallery placed right
  after badges, before the Table of Contents — readers see what the bot
  actually does before reading the architecture
  - 01-onboarding-and-vpn.webp — three-screen onboarding flow (greeting,
    privacy disclaimer, VPN-client picker)
  - 02-scan-and-report-delivery.webp — three-screen scan flow (start,
    VPN-key delivery modes, final report with HTML attachment)
- Sample scan report in two formats:
  - docs/reports/sample-scan-report.md — translated and anonymised real
    report (3 CRITICAL findings: SSH/Telnet/RTSP, 6 HIGH-severity threat
    IPs, traffic stats, recommendations) — Beginner-level rendering
  - docs/reports/sample-scan-report.html — same content as standalone
    HTML with inline dark-theme CSS, mobile-friendly — matches the file
    format the bot actually delivers
- Limitations & known failure modes section — 8 honest constraints
  (encrypted-payload blindness, JA3 evasion, detection lag, mobile-only,
  network-side only, VPN-trust requirement, false positives, no on-device
  remediation) — critical for a security tool's credibility
- Contact section with 4 explicit channels: live bot, Telegram for general,
  GitHub Issues for bugs/rules, email for security researchers /
  responsible disclosure / press / commercial
- Related — Claude Code ecosystem section cross-linking to all 7 sister
  repos by the same author (anti-regression-setup, ai-context-hierarchy,
  claude-statusline, notebooklm-claude-workflows, lingua-companion,
  diabot, ghost-showcase)
- Author signature expanded — full name (Nick Podolyak) + GitHub / Habr /
  dev.to / Telegram links — matches sister-repo standard
- Three new badges: Stars, Validate CI, "@secure_scanbot LIVE"
- CHANGELOG.md (Keep a Changelog) reconstructing showcase history
  (0.1.0 initial → 0.2.0 this PR) plus inline bot v2.3 changes
- CONTRIBUTING.md with Phase-2 readiness priorities (detection rules,
  manufacturer telemetry mapping, locales, Docker hardening, iOS rules,
  STIX2/MISP integrations) and explicit responsible-disclosure clause
- .github/workflows/validate.yml — LICENSE/CHANGELOG presence, every
  docs/* asset referenced from READMEs exists, HTML samples parse,
  internal Markdown links resolve, screenshot files are non-empty
- README.ru.md mirrored: same screenshots gallery, sample-report
  callout, Limitations, Contacts, Related, expanded author

Operational fix (separately, on production VPS)
- security-scanner-bot.service was crash-looping with status=203/EXEC
  since 2026-04-15 06:46 UTC because /root/security-scanner/venv/ had
  been removed from disk. systemd attempted 170,678 restarts before
  this fix. The venv has been recreated, dependencies reinstalled
  (aiogram 3.4.1, aiohttp 3.9.3, aiosqlite 0.19.0, nest_asyncio, plus
  the analysis stack), and the service is now active polling. Bot is
  live again at @secure_scanbot. Documented in CHANGELOG 0.2.0.

Excluded (deliberately)
- No rewrite of the existing 1,072-line README content — it was already
  the strongest among all author's repos (origin story, 4-layer detection
  engine, comparison table, real case study, AI adaptive reports). This
  PR is additive, not destructive.
- Default branch rename master→main deferred — invasive, affects
  external bookmarks
- awesome-claude-code submission — channel locked for non-collaborators

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@CreatmanCEO CreatmanCEO merged commit 6e5662e into master May 5, 2026
1 check passed
@CreatmanCEO CreatmanCEO deleted the polish-readme-and-meta branch May 5, 2026 10:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant